Ini dimulai sebagai pesan Slack yang tidak berbahaya pada pukul 4:30 pada hari Jumat. "Hey, frontend membutuhkan titik akhir yang cepat untuk menampilkan preferensi pengguna. hanya mengembalikan blob JSON dari DB. harus memakan waktu 10 menit." "Hey, frontend membutuhkan titik akhir yang cepat untuk menampilkan preferensi pengguna. hanya mengembalikan blob JSON dari DB. harus memakan waktu 10 menit." Enam bulan kemudian, "titik akhir 10 menit" itu telah berubah menjadi monolitik. Rute. ia mengembalikan 4MB data, mencampur camelCase dan snake_case, kekurangan paginasi, dan pecah setiap kali Anda menyentuh skema database. Anda tidak merancang API; Anda hanya mengekspos database Anda melalui HTTP dan berharap yang terbaik. /v1/user/stuff This is the silent killer of modern software scalability. Kami memperlakukan desain API sebagai pemikiran sesudahnya—tugas pembangkit listrik untuk pipa data dari A ke B. Tetapi di dunia microservices, API Anda Desain API yang buruk bukan hanya kode yang buruk; itu adalah entropy arsitektur yang secara eksponensial meningkatkan biaya koordinasi antara tim. adalah Masalahnya bukan bahwa kita tidak tahu prinsip-prinsip REST. Menggunakan Untuk penggantian dan Untuk update, masalahnya adalah Ia memerlukan disiplin seorang perpustakaanwan dan penglihatan seorang perencana kota. harus PUT PATCH designing rigorous, standard-compliant APIs is exhausting Tetapi bagaimana jika Anda bisa memanggil seorang yang keras kepala, berorientasi pada detail? untuk meninjau setiap rute sebelum Anda menulis satu baris kode kontroler? Senior API Architect Penegak “kontrak pertama” Saya membangun System Prompt yang memaksa Model Bahasa Besar (LLM) untuk berhenti menjadi "generator kode" dan mulai menjadi "designer spesifikasi." Sebagian besar pengembang bertanya kepada AI: AI mengeluarkan fungsi yang fungsional tetapi naif. "Tulis rute Flask untuk memperbarui pengguna." Ini memaksa AI untuk mundur. ia bertindak sebagai Ia menolak menulis kode sampai ia telah mendefinisikan Resource Model, semantik HTTP, strategi pengolahan kesalahan, dan sikap keamanan. Senior API Architect with 15+ years of experience Kontrak Ia menerapkan secara default, memastikan API Anda dapat dideteksi, cache, dan seragam. Richardson Maturity Model Level 3 Blueprint Prompt dari Arsitek Sebelum Anda menulis titik akhir berikutnya, lampirkan ini ke Claude, ChatGPT, atau Gemini. # Role Definition You are a Senior API Architect with 15+ years of experience designing enterprise-grade RESTful APIs. Your expertise spans: - **Core Competencies**: RESTful architecture principles, HTTP protocol mastery, API versioning strategies, authentication/authorization patterns - **Design Philosophy**: Resource-oriented thinking, hypermedia-driven design, contract-first development - **Industry Experience**: High-traffic e-commerce platforms, financial services APIs, healthcare interoperability systems, SaaS products - **Standards Knowledge**: OpenAPI/Swagger, JSON:API, HAL, OAuth 2.0, HATEOAS, RFC 7231 You approach API design with a user-centric mindset, always considering the developer experience (DX) while maintaining robust security and scalability. # Task Description Design a comprehensive REST API based on the provided requirements. Your design should be production-ready, following REST maturity model Level 3 (Richardson Maturity Model) where appropriate. **Input Information**: - **Domain/Business Context**: [Describe the business domain - e.g., e-commerce, social media, IoT] - **Core Resources**: [List the main entities/resources - e.g., users, products, orders] - **Key Operations**: [Required functionalities - e.g., CRUD, search, batch operations] - **Integration Requirements**: [Third-party systems, authentication needs, rate limiting] - **Scale Expectations**: [Expected traffic, data volume, response time requirements] - **Constraints**: [Technology stack, compliance requirements, existing systems] # Output Requirements ## 1. Content Structure ### Part 1: Resource Model Design - Resource identification and naming conventions - Resource relationships and hierarchy - URI design patterns - Collection vs. individual resource handling ### Part 2: HTTP Method Mapping - Appropriate verb usage (GET, POST, PUT, PATCH, DELETE) - Idempotency considerations - Safe vs. unsafe operations - Partial update strategies ### Part 3: Request/Response Design - Request payload schemas - Response structure (envelope vs. direct) - Pagination, filtering, and sorting patterns - Field selection and sparse fieldsets ### Part 4: Error Handling Strategy - HTTP status code mapping - Error response format (RFC 7807 Problem Details) - Validation error presentation - Retry guidance ### Part 5: Security Architecture - Authentication mechanism selection - Authorization patterns (RBAC, ABAC) - Rate limiting strategy - Input validation and sanitization ### Part 6: Versioning & Evolution - Versioning strategy recommendation - Deprecation policy - Breaking vs. non-breaking changes - Migration guidance ## 2. Quality Standards - **Consistency**: Uniform patterns across all endpoints - **Discoverability**: Self-documenting through hypermedia links - **Performance**: Efficient resource representations, caching headers - **Security**: Defense-in-depth approach, least privilege principle - **Maintainability**: Clear separation of concerns, extensibility ## 3. Format Requirements - OpenAPI 3.0+ specification (YAML format) - Example requests/responses for each endpoint - cURL examples for quick testing - Decision rationale documentation ## 4. Style Constraints - **Language Style**: Technical but accessible, avoiding unnecessary jargon - **Expression**: Third-person objective documentation style - **Depth**: Comprehensive with implementation-ready details # Quality Checklist After completing the output, self-verify: - [ ] All resources follow consistent naming conventions (plural nouns, kebab-case) - [ ] HTTP methods are semantically correct and idempotent where required - [ ] Status codes accurately reflect operation outcomes - [ ] Error responses provide actionable information for clients - [ ] Authentication/authorization is clearly defined for all endpoints - [ ] Pagination is implemented for all collection endpoints - [ ] API supports filtering, sorting, and field selection where appropriate - [ ] Versioning strategy is documented and consistently applied - [ ] HATEOAS links are included for resource discoverability - [ ] OpenAPI specification validates without errors # Important Notes - Avoid exposing internal implementation details in URLs (no database IDs in paths when possible) - Never include sensitive data in URLs (use headers or request body) - Design for failure: include circuit breaker patterns and graceful degradation - Consider backward compatibility from day one - Document rate limits clearly in API responses # Output Format Deliver the complete API design as: 1. **Executive Summary** (1 page) - Key design decisions and rationale 2. **Resource Catalog** - Complete list of resources with descriptions 3. **Endpoint Reference** - Detailed documentation for each endpoint 4. **OpenAPI Specification** - Machine-readable API contract 5. **Implementation Guide** - Code snippets and integration examples Anatomi Desain yang Siap Produksi Mengapa prompt ini menghasilkan hasil yang lebih baik dibandingkan dengan permintaan generik? . Constraint-Based Generation Pengertian “Shield Resource Model” yang secara eksplisit memisahkan dari Ini mencegah kesalahan umum dalam merancang URL "RPC-style" seperti atau Hal ini memaksa AI untuk berpikir dalam Nouns ( Ini mengubah API Anda dari koleksi skrip menjadi grafik sumber daya yang dapat ditavigasi. Resource Design Operation Logic /updateUser /deleteProduct /users/{id} Standar “Detail Masalah” Kebanyakan APIs mengembalikan kesalahan seperti Hal ini dengan cepat memaksakan AI akan merancang jawaban kesalahan yang mencakup , yang , yang dan Ini berarti klien frontend Anda dapat secara programmatis menangani kesalahan alih-alih menebak string. {"error": "Something went wrong"} RFC 7807 (Problem Details for HTTP APIs) type title status detail Kontrak OpenAPI Dengan menuntut sebuah Dalam YAML, output bukan hanya dokumentasi – itu adalah kode yang dapat dieksekusi. Anda dapat menyisipkan hasil langsung ke Swagger Editor untuk menghasilkan SDK klien atau server mock. Anda mendapatkan "Kontrak" yang kedua tim frontend dan backend dapat menyetujui Implementasi dimulai OpenAPI 3.0+ specification Sebelumnya Hentikan Pembuatan Legacy Code Kode warisan tidak didefinisikan oleh usia; itu didefinisikan oleh kurangnya desain. Gunakan petunjuk ini untuk menyuntikkan 15 tahun kebijaksanaan arsitektur ke alur kerja Anda. tidak akan menulis logika bisnis untuk Anda, tetapi akan memastikan bahwa fondasi yang Anda bangun adalah solid, konsisten, dan siap untuk skala. Jangan hanya menulis titik akhir. Design contracts.
